home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 1 / Gold Medal Software Volume 1 (Gold Medal) (1994).iso / prog / cextract.arj / CEXTRACT.TAR / cextract / cextrc.doc < prev    next >
Encoding:
Text File  |  1993-08-08  |  9.5 KB  |  331 lines
  1.  
  2.  
  3.  
  4. CEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
  5.  
  6.  
  7.  
  8. NAME
  9.      cextrc - C prototype/documentation  extractor  customization
  10.      file format
  11.  
  12. SYNOPSIS
  13.      .cextrc
  14.  
  15. DESCRIPTION
  16.      The programs cextract(1)  and  cextdoc(1)  extract  function
  17.      prototypes from C source code and create header and documen-
  18.      tation files respectively.  The .cextrc customization  files
  19.      allow  users to specify which options are set for those pro-
  20.      grams, without having to always use the command line.
  21.  
  22.      The configuration files are read prior to the parsing of the
  23.      command  line  options, as well as whenever the `-q' flag is
  24.      encountered.
  25.  
  26. FORMAT
  27.      The file should be a normal text file, with each  customiza-
  28.      tion  command  on a separate line.  Blank lines and any line
  29.      beginning with a `#' will be ignored.
  30.  
  31.      Any command preceded by the string "doc-only " will only  be
  32.      used  in  documentation  mode,  and  any command preceded by
  33.      "extract-only " will only be used in extraction mode.
  34.  
  35.      Commands which are preceded by either a `!'  or  the  string
  36.      "no-"  or "no" will be interpreted as disabling that option,
  37.      if appropriate.
  38.  
  39. COMMANDS
  40.      The full list of configuration commands is given below.
  41.  
  42.      ansi-code
  43.           If dual-output and merge-output modes are not  enabled,
  44.           produce output in ANSI C format, with full prototyping.
  45.           This command does not do anything when used in documen-
  46.           tation mode.
  47.  
  48.      break-after-types
  49.  
  50.      break-types
  51.           When enabled, a newline will be  inserted  between  the
  52.           function  type  and  the  function name in the function
  53.           declarations.
  54.  
  55.      comments
  56.  
  57.      yank-comments
  58.           Extract the comment  immediately  before  the  function
  59.           definition, and display it upon output.
  60.  
  61.  
  62.  
  63. Sun Release 4.1   Last change: 3 September 1992                 1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. CEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
  71.  
  72.  
  73.  
  74.      config-file: file
  75.           Read in the specified file and parse it for  configura-
  76.           tion commands.
  77.  
  78.      cpp-program: program
  79.           Specify which program is to be used as a  C  preproces-
  80.           sor.   This  program  should  resolve all C defines and
  81.           while, hopefully, leaving the comments intact.
  82.  
  83.      doc-mode
  84.           Enable documentation  mode  with  normal  text  output.
  85.           This is the default setting for cextdoc(1).
  86.  
  87.      define: expression
  88.           Pass the specified expression  to  the  C  preprocessor
  89.           with  a  "-D"  string prepended to it.  This command is
  90.           equivalent to the `-D' command line option.
  91.  
  92.      dual-output
  93.           Provide  output  in  both  ANSI  and  K&R  C   formats,
  94.           separated by an "#if __STDC__" ... "#else" ... "#endif"
  95.           construct.  This command does not do anything when used
  96.           in  documentation mode or if the merge-output option is
  97.           enabled.
  98.  
  99.      externs
  100.           Prepend an "extern" to each function  description  upon
  101.           output.
  102.  
  103.      extract-mode
  104.           Enable extraction mode and generate output which can be
  105.           used as a C header file defining the prototypes for all
  106.           of the functions which are  encountered.   The  is  the
  107.           default mode for cextract(1).
  108.  
  109.      first-comments
  110.           Include in the output the initial  comment  encountered
  111.           in each file.
  112.  
  113.      filename
  114.  
  115.      prepend-filename
  116.           If the "first-comments" option is enabled, prepend  the
  117.           name of each file to the output of initial comments.
  118.  
  119.      font % ##
  120.           Assign a troff font "##" to a given font type `%', when
  121.           using  troff  documentation  mode.   The  possible font
  122.           types are `1' or `t', `2' or `c', `3' or `n',  and  `4'
  123.           or `p' for the title, comment, name, and parameter list
  124.           respectively.  The troff font "##" is a normal  one  or
  125.           two  character  troff  font,  such  as "CO" for Courier
  126.  
  127.  
  128.  
  129. Sun Release 4.1   Last change: 3 September 1992                 2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. CEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
  137.  
  138.  
  139.  
  140.           Oblique.
  141.  
  142.      header-string: string
  143.           When in extraction  mode,  enclose  the  output  within
  144.           preprocessor  directives  testing for the definition of
  145.           string.  This method is used with  many  system  header
  146.           files,  to  insure  that  they are not "#include"d more
  147.           than once.  If this option is not used, the output will
  148.           be enclosed within a "#ifndef __CEXTRACT__", "#endif /*
  149.           __CEXTRACT__ */" sequence instead.
  150.  
  151.      include: directory
  152.           Pass the specified directory to the C preprocessor with
  153.           a  "-I"  string  prepended  to  it.   This  command  is
  154.           equivalent to the `-I' command-line option.
  155.  
  156.      merge-output
  157.           Merge the ANSI and K&R output into  a  single  line  of
  158.           output  to make it take up less space.  A macro is used
  159.           to expand the parameter list for ANSI compilers.   This
  160.           option  overrides  both  the  dual-output and ansi-code
  161.           options.  There is no affect if the documentation  mode
  162.           is enabled.
  163.  
  164.      multi-comments
  165.  
  166.      multiple-comments
  167.           When extracting comments, assume that consecutive  com-
  168.           ments  are  actually  one  single comment.  This allows
  169.           people that place comment delimiters at  the  beginning
  170.           and  end  of  each line to have their comments properly
  171.           captured.
  172.  
  173.      output-file: outfile
  174.           Store the output in the specified file.
  175.  
  176.      replace
  177.           Replace the first  string  which  matches  a  variable,
  178.           type,  or  both  (as  selected) with the second string.
  179.           The format is:
  180.                replace [all/type/variable] "string1" "string2"
  181.           For example, on  Sun  machines,  the  automatic  "FILE"
  182.           replacement could be accomplished using a command like:
  183.                replace type "struct _iobuf" "FILE"
  184.           However, this should not need  to  be  entered  by  the
  185.           average  user since it is handled automatically by cex-
  186.           tract(1), as is the varargs system.
  187.  
  188.      remove-names
  189.  
  190.      discard-names
  191.           Remove variable names from the prototype list prior  to
  192.  
  193.  
  194.  
  195. Sun Release 4.1   Last change: 3 September 1992                 3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. CEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
  203.  
  204.  
  205.  
  206.           output.
  207.  
  208.      roff-mode
  209.  
  210.      troff-mode
  211.           Enable documentation mode with troff -ms format output.
  212.           This  option  is overridden by the doc-mode or extract-
  213.           mode options.
  214.  
  215.      show-all
  216.  
  217.      show-anyway
  218.           When output is K&R C, display prototypes  in  comments.
  219.           When  dual-output is enabled, display comments and pro-
  220.           totypes in both sections; otherwise,  display  comments
  221.           and prototypes only in the ANSI C portion.  This option
  222.           does nothing in documentation mode.
  223.  
  224.      single-comments
  225.           When extracting comments from a  file,  take  only  one
  226.           comment,   discarding  all  preceding  comments.   This
  227.           option is the reverse of the multi-comments option.
  228.  
  229.      sort-all
  230.           Alphabetically sort all of the functions  from  all  of
  231.           the files before generating output.
  232.  
  233.      sort-by-files
  234.           For each file processed,  sort  all  of  the  functions
  235.           prior to output.
  236.  
  237.      statics
  238.  
  239.      statics: none
  240.  
  241.      statics: any
  242.  
  243.      statics: only
  244.           Select the method for how static  functions  should  be
  245.           treated.   If  "none"  is  selected,  statics  will  be
  246.           ignored.  If "only" is selected,  non-static  functions
  247.           will  be  ignored.   Finally,  "any" indicates that all
  248.           functions will be extracted.  If no selection is  made,
  249.           it  will  be  the  same  as  selecting "any" or (with a
  250.           preceding `!') "none".
  251.  
  252.      tab-width: width
  253.           Set the tab width to be an integer number width.   This
  254.           works only during documentation generation.
  255.  
  256.      undefine: name
  257.           Undefine any previously  defined  macro.   If  none  is
  258.  
  259.  
  260.  
  261. Sun Release 4.1   Last change: 3 September 1992                 4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. CEXTRC(5)                 FILE FORMATS                  CEXTRC(5)
  269.  
  270.  
  271.  
  272.           encountered,  pass  the  specified  expression to the C
  273.           preprocessor with a "-U" string prepended to it.   This
  274.           command is equivalent to the `-U' command-line option.
  275.  
  276.      wrap-parameters: #
  277.           If the length of the  parameter  list  for  a  function
  278.           would  cause it to exceed a given number of columns [72
  279.           by default], a newline will be inserted in place  of  a
  280.           space  character,  so that the function will not exceed
  281.           that given length.  The optional number after the  com-
  282.           mand will override a negation prefix if encountered.
  283.  
  284. FILES
  285.      /usr/local/lib/cext.config, $HOME/.cextrc, .cextrc
  286.           configuration files.
  287.  
  288. VMS
  289.      Configuration files  are  also  supported  under  VMS.   The
  290.      default    configuration   files   for   VMS   systems   are
  291.      sys$library:cext.cnf, sys$login:cext.cnf, and cext.cnf.
  292.  
  293.      Since the VMS C compiler strips out comments, the documenta-
  294.      tion  mode  and  comment options are not very useful.  Using
  295.      the GNU C preprocessor instead might be a possible solution.
  296.  
  297. SEE ALSO
  298.      cextract(1), cextdoc(1)
  299.  
  300. AUTHOR
  301.      Adam Bryant
  302.      adb@bu.edu
  303.  
  304.      initial VMS port by John Carr
  305.      jrcarr@iup.bitnet
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327. Sun Release 4.1   Last change: 3 September 1992                 5
  328.  
  329.  
  330.  
  331.